/******************************************************************************************
文件名：ringbuffer.h
作者：狼狼    版本：V1.0    创建日期：2021.8.1
文件描述：
    头文件。
历史修改记录：
1. 2021-8-1:V1.0 狼狼
创建。
2. 2022-5-11:V1.0 狼狼
代码公开。
******************************************************************************************/
#ifndef RING_BUFFER__
#define RING_BUFFER__
//+------------------------------------------------------------------------------------------+
//|                                           头文件
//+------------------------------------------------------------------------------------------+
/*|*/#include <stdint.h>
/*|*/#include <pthread.h>
//+------------------------------------------------------------------------------------------+
//|                                           宏开关
//+------------------------------------------------------------------------------------------+
//|    ----------------------------------------
//|    NOTE:当前宏被定义后，若添加数据时数据长
//|         度超出缓冲区剩余空间则返回错误，错
//|         误码(RINGBUF_ERROR_UNEXPECT_DATA_LENGTH)；
//|         当前宏未被定义时，若添加数据时数据
//|         长度超出缓冲区剩余空间则缓冲区将仅
//|         拷贝数据直至缓冲区满，返回实际拷贝
//|         字节数。
//|    ----------------------------------------
/*|*/#define RINGBUF_SWITCH_ADD_DATA_ALL
//+------------------------------------------------------------------------------------------+
//|                                         参数宏定义
//+------------------------------------------------------------------------------------------+
/*|*/#define RINGBUF_SUCCESS                      0x00000000
//|    ----------------------------------------
//|    错误码：非法的参数
//|    ----------------------------------------
/*|*/#define RINGBUF_ERROR_ILLEGAL_PARAM          0x90001001
//|    ----------------------------------------
//|    错误码：申请内存失败
//|    ----------------------------------------
/*|*/#define RINGBUF_ERROR_MALLOC                 0x90001002
//|    ----------------------------------------
//|    错误码：互斥锁操作失败
//|    ----------------------------------------
/*|*/#define RINGBUF_ERROR_METUX                  0x90001003
//|    ----------------------------------------
//|    错误码：条件变量操作失败
//|    ----------------------------------------
/*|*/#define RINGBUF_ERROR_COND                   0x90001004
//|    ----------------------------------------
//|    错误码：当前缓冲区状态不支持此操作
//|    ----------------------------------------
/*|*/#define RINGBUF_ERROR_UNEXPECT_STATE         0x90002001
//|    ----------------------------------------
//|    错误码：待存入的数据长度超出合法范围
//|    ----------------------------------------
/*|*/#define RINGBUF_ERROR_UNEXPECT_DATA_LENGTH   0x90002002
//|    ----------------------------------------
//|    错误码：待更新的数据长度超出合法范围
//|    ----------------------------------------
/*|*/#define RINGBUF_ERROR_UNEXPECT_UPDATE_LENGTH 0x90002003
//+------------------------------------------------------------------------------------------+
//|                                          数据类型
//+------------------------------------------------------------------------------------------+
//|    ----------------------------------------
//|    用于描述缓冲区状态的枚举类型
//|    NOTE:仅内部使用
//|    ----------------------------------------
/*|*/typedef enum ring_buffer_state
/*|*/{
/*|*/    RINGBUF_STAT_INIT = 0,
/*|*/    RINGBUF_STAT_OK,
/*|*/    RINGBUF_STAT_DISABILED,
/*|*/}ENUM_RING_BUFFER_STATE;
//|
//|    ----------------------------------------
//|    用于存储一个缓冲区对象必要信息的结构
//|    ----------------------------------------
/*|*/typedef struct ring_buffer
/*|*/{
//|    ----------------------------------------
//|    指向堆内存空间的指针
//|    ----------------------------------------
/*|*/  uint8_t *pbuf;
//|    ----------------------------------------
//|    缓冲区总容量信息
//|    ----------------------------------------
/*|*/  uint32_t capacity;
//|    ----------------------------------------
//|    读指针位置
//|    ----------------------------------------
/*|*/  uint8_t *pread_pos;
//|    ----------------------------------------
//|    写指针位置
//|    ----------------------------------------
/*|*/  uint8_t *pwrite_pos;
//|    ----------------------------------------
//|    缓冲区已用空间大小
//|    ----------------------------------------
/*|*/  uint32_t used_space;
//|    ----------------------------------------
//|    缓冲区剩余空间大小
//|    ----------------------------------------
/*|*/  uint32_t unused_space;
//|    ----------------------------------------
//|    缓冲区操作互斥锁
//|    ----------------------------------------
/*|*/  pthread_mutex_t mutex;
//|    ----------------------------------------
//|    用于缓冲区条件变量的互斥锁
//|    ----------------------------------------
/*|*/  pthread_mutex_t cond_mutex;
//|    ----------------------------------------
//|    用于向外部进行通知的条件变量
//|    ----------------------------------------
/*|*/  pthread_cond_t cond;
//|    ----------------------------------------
//|    缓冲区状态信息
//|    ----------------------------------------
/*|*/  ENUM_RING_BUFFER_STATE state;
//|    ----------------------------------------
//|    回调函数集
//|    NOTE:以下函数指针在初始化缓冲区对象时被
//|         赋值。
//|    ATTENTION:使用缓冲区结构对象成员函数指针
//|              前必须先对其进行初始化！
//|    ----------------------------------------
/*|*/  int (*add_data)         (struct ring_buffer * const buf, const uint8_t *pdata, uint32_t len);
/*|*/  int (*get_data_len)     (struct ring_buffer * const buf, uint32_t *plen);
/*|*/  int (*get_data_point)   (struct ring_buffer * const buf, uint8_t **ppdata);
/*|*/  int (*update_data_point)(struct ring_buffer * const buf, uint32_t len);
/*|*/  int (*wait_for_data)    (struct ring_buffer * const buf);
/*|*/  int (*switch_to_disable)(struct ring_buffer * const buf);
/*|*/  int (*switch_to_enable) (struct ring_buffer * const buf);
/*|*/  int (*clear)            (struct ring_buffer * const buf);
/*|*/  int (*get_used_space)   (struct ring_buffer * const buf, uint32_t *plen);
/*|*/  int (*get_unused_space) (struct ring_buffer * const buf, uint32_t *plen);
/*|*/}ST_RING_BUFFER;
//+------------------------------------------------------------------------------------------+

#ifdef __cplusplus
extern "C" {
#endif
//+------------------------------------------------------------------------------------------+
//|                                       函数/变量声明
//+------------------------------------------------------------------------------------------+
/*|*/int ring_buffer_create(ST_RING_BUFFER *buf, uint32_t capacity);
/*|*/int ring_buffer_destroy(ST_RING_BUFFER *buf);
//+------------------------------------------------------------------------------------------+
#ifdef __cplusplus
}
#endif /* End of __cplusplus*/

#endif /* End of #define RING_BUFFER__ */
